Mac Format 1996 April/MacFormat CD Edition MF36 (April 1996).iso/Shareware City/Developers/Tools Plus - GUI⁄Event libs/Tools Plus 2.6.1a Evaluat'n Kit/Tools Plus 2.6.1a/User Manual/07-Picture Buttons (1 of 3)

INI File | 1994-09-17 | 22KB | 264 lines

[Display using Monaco 9]


7  Picture Buttons
``````````````````

  Tools Plus supports the use of picture buttons on any Tools Plus window.  Picture buttons allow an icon (of any type) or picture (PICT resource) to be used as a button.  Picture buttons also allow the use of multiple images (icons or PICTs) to produce buttons whose appearance changes depending on whether the button is selected, disabled, or if its value changes.  (Please note that within this chapter, the term button is used to refer to a picture button unless otherwise stated.)

  The designing of attractive buttons is simplified with the use of Tools Plus’s 3D picture buttons, which let you design a black and white (1-bit) image, then Tools Plus takes care of transforming it into an elevated 3D color button, much like the kind seen in the tool bars of many commercial software packages.  When selected, these buttons appear to be pushed into the window with appropriate shading and highlighting.

  Picture buttons are created on the current window by the NewPictButton procedure.  Each picture button is referenced by a unique picture button number, which can be from 1 to 255.  This number is specified when the picture button is created, and refers to the specific picture button until that button is deleted.  Note that the button’s number is related to its associated window.  This means that two different windows can each have a picture button numbered “1” without interfering with each other.  Whenever a picture button is clicked by the user, the PollSystem function reports the picture button number as well as its window number.

  The support of color and multiple monitors is automatic, so Tools Plus’s picture buttons will always be drawn using the most appropriate image, even if the button straddles the boundary of multiple monitors.

  When a picture button is no longer required, it is deleted by the DeletePictButton procedure, which releases the memory used by that button.  This is done automatically if a window is closed.





Button Types
````````````
  Various types of picture buttons can be created, incorporating different behavioral characteristics and appearances.  In the simplest implementation, a picture button can be used merely as a “click-sensitive” icon that reports an event when it is selected by the user.  Picture buttons can also be used to functionally replace the standard push buttons, check boxes, or radio button groups.  More importantly, picture buttons are more than a cosmetic user interface enhancement; in many cases they provide a stronger metaphor for tasks at hand (such as a “power on/power off” switch).  The following are just a few examples of the types of picture buttons that can be created:

  • Click-Sensitive Icons
  • Push Button
  • Multistage Buttons (diffent look per button value)
  • Radio Button Set (Exclusive Selection)
  • Check boxes
  • Polarized (One side increases its value, the other decreases)
  • Click-On/Click-Off
  • Analog Simulations





Button Behavior
```````````````

  When you create a picture button, you must specify its behavioral characteristics.  These characteristics define how the button operates when it is clicked by the user, as well as other properties the button has.  Although the behavior specification is detailed by the NewPictButton procedure, some of the choices you have are as follows:

  • Does the button report an event when the mouse is first pressed down
    in the button, or does it wait for the mouse button to be released?

  • Does the button lock in the “selected” position?

  • Does the button produce repeated events when it is held down?

  • How quickly does the button’s value change?

  • Is the button polarized? (One side increases its value, the other
    decreases)

  • Are PICTs used, or icons?

Please see the NewPictButton procedure for details describing all the behavioral options at your disposal.





Selection Effects
`````````````````
  An enabled button can be selected by the user by clicking on the button.  Your application can also select or deselect any button by using the SelectPictButton procedure.  By default, Tools Plus darkens the button’s image to make it appear selected, but you can override this effect individually for each button.  Instead of darkening the image, you can provide an alternate image of the selected button.  This is particularly effective if you are trying to produce the illusion of three dimensional controls.  A complete description of selection effects is provided within the NewPictButton documentation.

  Tools Plus’s 3D picture buttons require only a single black and white icon to produce all the necessary three dimensional effects in color.  They also provide you with several selection effects, all of which include the button being pushed into the window when it is selected.





Disabling Effects
`````````````````
  All picture buttons can be enabled or disabled by using the EnablePictButton procedure.  When a button is disabled, it cannot be selected by the user.  By default, Tools Plus overlays the image with a black color using a light gray pattern (25%) to make the button appear disabled (as does the Finder), but you can override this effect individually for each button.  See the DefaultIconLook procedure for details on setting disabled images’ default appearance.  Instead of applying the default disabling effect, you can provide an alternate image of the disabled button.  This option provides you with the ultimate control over a button’s appearance.  A complete description of disabling effects is provided within the NewPictButton documentation.

  Tools Plus’s 3D picture buttons require only a single black and white icon to produce all the necessary three dimensional effects in color.  When disabled, these buttons are automatically dimmed and “embossed” to provide a functional and attractive depiction of a disabled button.





Button’s Value and Stages
`````````````````````````
  Each picture button has an associated value, and range defined by an upper and lower limit of that range (a minimum value and maximum value).  Buttons that are only concerned with being selected or disabled do not have to set or report button values.  Other buttons, such as a picture button that controls the rotation of an object through 360°, need a current value that will fall within the button’s value range.  Your application can obtain the button’s value at any time, or in response to an event.

  Each button that has a range of values, even simple on/off buttons that have a small range (off=0 and on=1), can optionally be defined as a multistage picture buttons.  A multistage button has a different image for each stage.  For example, a “Cutting Tool” button may have three stages, each of which has a different image for the different kinds of cutting tools available:
  • Stage 1: Scissors image
  • Stage 2: Knife image
  • Stage 3: Axe image

  In a multistage button, there is a “stage” for each value in the button’s range.  Within each stage, the button potentially has four states: enabled/deselected, enabled/selected, disabled/deselected, and disabled/selected.

  Multistage buttons should be used with discretion, since the buttons’ values are serial and the user cannot skip directly to a value.  You can imagine the difficulty that a user would experience if they were forced to step through a dozen stages.  Generally, three to five stages are the practical limits for a user interface.  If you need more stages, consider using a more appropriate control, like a pop-up menu.

  Single stage picture buttons can have any value that lies within their upper and lower limit.  Multistage buttons use the button’s value to determine the current stage, therefore their value must also lie within their upper and lower limit.





Handling Picture Buttons
````````````````````````
  Your application specifies if picture buttons are selected or deselected, and if they are enabled or disabled.  When a window in inactive, Tools Plus disables all of its picture buttons.  When the window is activated again, all the buttons regain their correct status as specified by your application.

  The PollSystem function is used to constantly inquire about any events that have occurred, including clicking on picture buttons.  If a button is selected (i.e., the user presses the mouse button down and releases it within the button’s region), it is reported by PollSystem.  If the button is configured to report an “instant” event, your application will be informed as soon as the mouse-down occurs in the picture button.  Picture buttons that are configured to produce repeating events will produce events while the picture button is held down and the cursor is in the button.

  When working with picture buttons that function like Radio Buttons (those that lock in the “selected” position), Tools Plus doesn’t know how these buttons are grouped, and therefore does not automatically turn off other picture buttons.  Your application must handle this.

------------------------------------------------------------------------

NewPictButton
`````````````
Create a new picture button.

   pascal void NewPictButton (short Button, short left, short top,
                 short BaseID, long procID,
                 Boolean EnabledFlag, Boolean SelectedFlag,
                 short minimum, short value, short maximum);

   procedure NewPictButton (Button, left, top, BaseID: INTEGER;
                 procID: LONGINT; EnabledFlag, SelectedFlag: BOOLEAN;
                 minimum, value, maximum: INTEGER);

  Button specifies the picture button number (from 1 to 255) that is created in the current window.  Once a picture button is created, it is referenced by this picture button number.  If a picture button has been previously created in the current window using the same number, it is replaced with a new picture button as specified by the parameters in the NewPictButton procedure.  If the current window doesn’t belong to your application, or if no windows are open, NewPictButton does nothing.

  Left and top define the top left-hand corner of the picture button in window’s local co-ordinates.  The button’s images define the size of the button.

  BaseID specifies the base resource ID number of the icon (any type) or PICT used by the picture button.  All other image resources used by this button will be numbered higher than this one.  See “Resource IDs” later in this section for a detailed description of image resource numbering.

  ProcID is the picture button’s behavior and appearance specification.  It is used by the button to determine its behavioral characteristics, and how it looks when selected or deselected, enabled or disabled, and when the button’s value is changed.  See “Behavior and Appearance Specification” later in this section for a detailed description of how the value for this item is determined.

  The EnabledFlag indicates if the newly created picture button is enabled or not.  When a picture button is disabled, it cannot be selected by the user.  All picture buttons automatically become disabled when the window containing them is inactive.  When the window is activated, the picture buttons assume their state as set by the NewPictButton procedure and subsequent calls to the EnablePictButton procedure.  The two constants that can be used for this flag are enabled and disabled.

  The SelectedFlag indicates if the newly created picture button is selected or not.  The two constants that can be used for this flag are selected and notSelected.

  Minimum declares the picture button’s minimum value limit.  In multistage buttons, the first stage starts at this minimum limit.  Use zero (0) if your button’s value does not change.

  Value defines the picture button’s current value.  The current value must be greater than or equal to the minimum limit, and less than or equal to the maximum limit.  Use zero (0) if your button’s value does not change.

  Maximum declares the picture button’s maximum value limit.  The maximum limit must be greater than the minimum limit.  In multistage buttons, use this upper limit to define the total number of available stages (i.e., Maximum = Minimum + Total Stages - 1).  Use zero (0) if your button’s value does not change.

Note: Tools Plus makes no attempt to control the placement of picture
      buttons or to protect them once they have been created.  It is
      your responsibility to ensure that picture buttons are placed
      within the window as to not conflict with other objects.
      Furthermore, you should not allow your application’s text and
      drawing processes to interfere with picture buttons.  Windows with
      a “size box” should not allow picture buttons to be obscured or
      hidden by making the window too small.



Resource IDs
````````````
  Picture buttons can use PICTs or icons of any kind for a button’s image.  Multiple buttons can also share the same resources.  When you are designing images for your buttons, make sure you adhere to the resource numbering schemes detailed in this section.  The numbering system is based on “stages” with each stage having a block of resource IDs.  The relative resource ID in each stage (i.e., the third resource in each stage) performs the same function, the only difference being the stage number (which correlates to the button’s value).  For example, the first image in each stage is the button’s image as an enabled, deselected button.  The first image in stage 1 is for an enabled, deselected button with the button’s minimum value.  The first image in stage 2 is for an enabled, deselected button with the button’s minimum value + 1.

  Picture buttons can also incorporate a mask, which is useful if the button uses images that are not rectangular, or if it uses a set of images that vary in size.  If a mask is provided, the button’s image is limited to the mask’s region, as will the user’s mouse clicks.  See the DrawIcon routine for a detailed description of how a mask works.



Icon Resource IDs
`````````````````
  If you are going to use icons for picture button images, you must first have an understanding of an icon family.  An icon family is a set of icons (of any type) that share the same resource ID number.  From a picture button’s point of view, all the images in an icon family are all the same image with the only difference being the suitability of a particular icon for the target monitor’s settings.

  Tools Plus’s picture buttons will always select the best possible image for the button, depending on the monitor’s settings.  This is true even if the button straddles multiple monitors.  See the DrawIcon routine for a detailed description of each icon, and the sequence in which they are accessed by Tools Plus.

  The following chart  describes the icon resource numbering sequence that must be followed when creating images for picture buttons:

            ============+=============+==========+=========
                        |   Icon ID   | Selected | Enabled
            ============+=============+==========+=========
               Stage #1 |   Base ID   |     N    |    Y
            (min. limit)| Base ID + 1 |     Y    |    Y
                        | Base ID + 2 |     N    |    N
                        | Base ID + 3 |     Y    |    N
            ------------+-------------+----------+---------
               Stage #2 | Base ID + 4 |     N    |    Y

       Note: Multistage 3D buttons using the SICN resource require
       only 1 resource for all possible combinations and stages



  When you are creating icons for your picture button, be aware that you do not have to create an icon for each possible combination of being selected/deselected and enabled/disabled.  If your button uses an alternate image as a selection effect, you will need to create an image for the selected button (Base ID + 1).  If your button uses an alternate image as a disabling effect, you will have to create an image for the disabled button (Base ID + 2).  And if your button uses an alternate image for both selecting and disabling, you will have to create an image for the selected, disabled button (Base ID + 3).  If you are creating a multistage button, you will have to create similar images for each stage (note that your button can have a range of values and still be a single stage button.)



3D SICN Buttons
```````````````
  A unique feature is available in Tools Plus’s picture buttons that allows you to create 3D color buttons by simply designing a black and white icon.  This is accomplished by using an SICN resource.  A single SICN resource is capable of storing multiple icon images, and is therefore particularly well suited for multistage buttons.

  If you are using an SICN resource to create a 3D button, you only need to create one resource for the button (Tools Plus formulates all the necessary selected and disabled images).  If the button has multiple stages, create one icon within the that SICN resource for each stage.

Note: To avoid icon conflicts while you are developing your application,
      do not create icon numbers that are used by your development
      environment (THINK C or THINK Pascal).  THINK C and THINK Pascal
      sometimes supply their own icons in place of those in your
      resource file whenever icon numbers coincide.
        You can create and edit icons with a resource editor such as
      Apple’s ResEdit.  When you create icons, remember to use ID
      numbers 128 or higher.  The rest are reserved numbers.



PICT Resource IDs
`````````````````
  The numbering scheme used for PICTs is similar to the one used for icons, except that it is not possible to create several PICTs (to account for different monitor settings) with the same resource ID number.  Therefore, a button’s PICTs are numbered in such a way as to preserve the trend established by the icon’s numbering scheme, and to account for multiple PICTs that are required for different screen depths.

  Tools Plus’s picture buttons will always select the best possible PICT image for the button, depending on the monitor’s settings.  This is true even if the button straddles multiple monitors.

  The following chart describes the PICT resource numbering sequence that must be followed when creating images for picture buttons:


      =============+===========+==============+==========+========
                   | Scr Depth |   PICT ID    | Selected | Enabled
      =============+===========+==============+==========+========
      Stage #1     |    B&W    |   Base ID    |     N    |    Y
      (min. limit) |   4-bit   | Base ID + 1  |          |
                   |   8-bit   | Base ID + 2  |          |
                   |   Mask    | Base ID + 3  |          |
                   +-----------+--------------+----------+--------
                   |    B&W    | Base ID + 4  |     Y    |    Y
                   |   4-bit   | Base ID + 5  |          |
                   |   8-bit   | Base ID + 6  |          |
                   |   Mask    | Base ID + 7  |          |
                   +-----------+--------------+----------+--------
                   |    B&W    | Base ID + 8  |     N    |    N
                   |   4-bit   | Base ID + 9  |          |
                   |   8-bit   | Base ID + 10 |          |
                   |   Mask    | Base ID + 11 |          |
                   +-----------+--------------+----------+--------
                   |    B&W    | Base ID + 12 |     Y    |    N
                   |   4-bit   | Base ID + 13 |          |
                   |   8-bit   | Base ID + 14 |          |
                   |   Mask    | Base ID + 15 |          |
      -------------+-----------+--------------+----------+--------
      Stage #2     |    B&W    | Base ID + 16 |     N    |    Y



  When you are creating PICTs for your button, be aware that you do not have to create a PICT for each possible combination of being selected/deselected and enabled/disabled, or color.  If your button uses an alternate image as a selection effect, you will need to create an image for the selected button (Base ID + 4 through 7).  If your button uses an alternate image as a disabling effect, you will have to create an image for the disabled button (Base ID + 8 through 11).  And if your button uses an alternate image for both selecting and disabling, you will have to create an image for the selected, disabled button (Base ID + 12 through 15).  If you are creating a multistage button, you will have to create similar images for each stage (note that your button can have a range of values and still be a single stage button.)

  Always create a PICT for the black and white image.  Depending on your requirements, you may choose not to have color PICTs for 4-bit or 8-bit monitor settings.

  The mask is optional in all cases, but is recommended in cases when the button is irregularly shaped, or if all the PICTs used by a button are not the same size.  Tools Plus also recognizes that in many cases, masks will be identical between stages, and possibly between selected/deselected and enabled/disabled buttons.  A picture button will try to find a mask that corresponds to its current selection and enabled state.  If the appropriate mask can’t be found (because the correctly number PICT resource does not exist), it will try to use substitute masks based on the following rules:

  • If the button is disabled, try to find the equivalent “enabled” mask
    in the same stage

  • If the button is selected, try to find the equivalent “deselected”
    mask in the same stage

If a multistage button is not at its minimum stage…

  • If the button is disabled, try to find the equivalent “enabled” mask
    in the minimum stage

  • If the button is selected, try to find the equivalent “deselected”
    mask in the minimum stage